home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1994 November: Tool Chest / Dev.CD Nov 94.toast / Sample Code / Newton Sample Code 1.2 / System Services / FalseAlarm-2 / AlarmPkgUtil.README < prev    next >
Encoding:
Text File  |  1994-04-29  |  4.3 KB  |  123 lines  |  [TEXT/R*ch]

  1. /*
  2.  
  3. Copyright: © Apple Computer, Inc. 1994
  4.  
  5. author: Mike Engber
  6.  
  7. AlarmPkgUtil - v6
  8.  
  9. Version History
  10.  
  11. v5
  12.   - beta seeding release
  13. v6
  14.   - first general release
  15.   - fixed EnsureInternal bug that could cause -10401 errors
  16.   - new icon
  17.  
  18. v7
  19.   - uses new alarm stub which fixes an obscure problem:
  20.      If you remove a card containing the Calendar meeting
  21.       with an alarm AND none of the internally stored meetings
  22.       have alarms set - all alarms get cancelled.
  23.   - detects old stub and allows you to replace it
  24.   - handles case where alarm API is built-in to the ROM
  25.   - does not report an error when it detects the SystemAlarmSoup,
  26.     but the alarm stub not installed. This can happen if the user
  27.     does a cold boot and then a restore (SystemAlarmSoup is restored,
  28.     but not the stub)
  29.  
  30.  */
  31.  
  32.  
  33. Background
  34.  
  35. The code for adding alarm functionality to a Newton is in the NTK
  36. platform file. It is automatically installed (if necessary) in a
  37. Newton whenever you use one of the following functions:
  38.  
  39.     kAddAlarmFunc
  40.     kRemoveAlarmFunc
  41.     kGetAlarmFunc
  42.     kGetAppAlarmKeysFunc
  43.     kRemoveAppAlarmsFunc
  44.  
  45. It is installed in the internal user store of the Newton. (uses ~4K) This
  46. installation is permanent - until the user does a cold boot.
  47.  
  48. This is a very serious matter. Your users need to be warned they may
  49. lose ~4K of internal storage if they use your app. Of course, this
  50. storage is not lost every time your app is run or for every different
  51. app that uses alarms. It is lost only once, when the alarm functionality
  52. is initially installed.
  53.  
  54. On ROMs that have the alarm functionality built in - the installation is
  55. not necessary and will not take place. The current Message Pad ROMs do
  56. not have the alarm functionality built in.
  57.  
  58. The alarm API is currently the only set of funcitons in the NTK platform
  59. file that does this type of permanent installation. Alarms are a special
  60. case. Many apps require the alarm functionality to persist in the Newton
  61. even if the app is not installed (e.g. on a card that has been removed).
  62. This means the code for the alarm API cannot simply reside in your app's
  63. package as is the case for the other APIs in the platform file.
  64.  
  65.  
  66.  
  67. Intro
  68.  
  69. AlarmPkgUtil is an app for programmers to use in testing their alarm
  70. code. It allows you to explictitly install/remove the alarm
  71. functionality into a Newton - something your users will be unable to
  72. do.
  73.  
  74. You will want to use AlarmPkgUtil in order to test your app's robustness.
  75. E.g. test your app with the alarm functionality already installed, not
  76. previously installed, becoming installed while your app is already
  77. running, ...
  78.  
  79. DO NOT DISTRIBUTE AlarmPkgUtil to your users. Allowing users to remove
  80. alarm functionality from the Newton will introduce all sorts of subtle
  81. problems you don't want to deal with - believe me.
  82.  
  83.  
  84. Usage
  85.  
  86. The UI to AlarmPkgUtil should be self explanitory. There is only a single
  87. button that is labeled either "Install Alarm Package" or "Remove Alarm
  88. Package" whichever is appropriate.
  89.  
  90. There is a status box below which tells you the current state of the
  91. system wrt the alarm functionality. If the state is *error*, the box
  92. will contain a list of items (each preceded by a + or -). This
  93. information will be useful to me in debugging any problems you
  94. encounter.
  95.  
  96.  
  97.  
  98. Warnings
  99.  
  100. -If you have the AlarmEnabler.pkg (from the first beta seed of the alarm
  101. API) installed or you have not reset since you removed it, then the
  102. AlarmPkgUtil may show an *error* state. Remove the AlarmEnabler.pkg and
  103. reset your Newton.
  104.  
  105.  
  106. -Alarm functionality may not be added to a Newton during an InstallScript
  107. or a RemoveScript. This means, if the alarm functionality is not already
  108. present in the Newton and you use one of the 5 alarm API functions - it
  109. may not succeed. (the Newton may hang in this situation - a reset will
  110. necessary)
  111.  
  112. You can avoid this problem entirely by not using the alarm api during
  113. your install or remove scripts. Alternately, you can spawn deferred actions
  114. from your install/remove scripts to do your alarm related tasks.
  115.  
  116.  
  117. -It is important that you do not delete the alarm soup. If you do so, you
  118. will need to cold boot your Newton before AlarmPkgUtil will function
  119. properly. We are not documenting any details about the alarm soup - you
  120. should only interact with it through the alarm API functions.
  121. (Using AlarmPkgUtil to remove the alarm functionality does remove the
  122. alarm soup for you - safely)
  123.